<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Events | Framework7 Documentation</title>
    <meta property="og:image" content="http://framework7.io/i/f7-banner.jpg">
    <meta name="viewport" content="width=device-width, viewport-fit=cover">
    <meta name="twitter:card" content="summary">
    <meta name="twitter:site" content="@framework7io">
    <meta name="twitter:creator" content="@framework7io">
    <meta name="twitter:title" content="Events | Framework7 Documentation">
    <meta name="twitter:image" content="https://avatars0.githubusercontent.com/u/31954178?s=200&amp;v=4">
    <link rel="stylesheet" href="/framework7-v3/css/normalize.css">
    <link rel="stylesheet" href="/framework7-v3/css/main.css">
    <link rel="shortcut icon" href="/framework7-v3/i/favicon.png">
    <script src="/framework7-v3/js/modernizr-2.7.1.min.js"></script>
  </head>
  <body class="body-docs">
    <header class="internal-header">
      <div class="center">
        <div class="logo-holder"><a class="logo" href="/framework7-v3/"></a></div>
        <div class="header-content">
          <div class="title">Framework7
            <div class="version">v3.6.7</div>
          </div>
          <ul class="nav">
            <li><a href="/framework7-v3/docs/">Docs</a>
              <ul>
                <li><a href="/framework7-v3/docs/introduction.html">Getting Started</a></li>
                <li><a href="/framework7-v3/docs/">Framework7 Core / API</a></li>
                <li><a href="/framework7-v3/vue/">Framework7 Vue</a></li>
                <li><a href="/framework7-v3/react/">Framework7 React</a></li>
                <li><a href="https://framework7.io/icons/" target="_blank">Framework7 Icons</a></li>
                <li><a href="/framework7-v3/docs/dom7.html">Dom7</a></li>
                <li><a href="http://idangero.us/template7/" target="_blank">Template7</a></li>
              </ul>
            </li>
            <li><a href="#">Resources</a>
              <ul>
                <li><a href="http://forum.framework7.io" target="_blank">Community Forum</a></li>
                <li><a href="https://framework7.io/tutorials/" target="_blank">Tutorials</a></li>
                <li><a href="https://framework7.io/templates/" target="_blank">Templates</a></li>
                <li><a href="https://framework7.io/plugins/" target="_blank">Plugins</a></li>
                <li><a href="https://framework7.io/showcase/" target="_blank">Apps Showcase</a></li>
                <li><a href="https://jobs.framework7.io" target="_blank">Jobs & Developers</a></li>
              </ul>
            </li>
            <li><a href="http://blog.framework7.io" target="_blank">Blog</a></li>
            <li><a href="https://framework7.io/contribute/" target="_blank">Contribute</a></li>
          </ul>
          <div class="patreon-github"><a class="patreon-button" href="https://www.patreon.com/vladimirkharlampidi" target="_blank"><span class="patreon-logo"></span><span class="patreon-text">Support Framework7</span></a>
            <div class="github-buttons"><a href="https://github.com/framework7io/framework7/" target="_blank"><img src="/framework7-v3/i/gh-logo.png"></a><a class="gh-stars" href="https://github.com/framework7io/framework7/" target="_blank"><span></span> stars</a><a class="gh-forks" href="https://github.com/framework7io/framework7/" target="_blank"><span></span> forks</a></div>
          </div>
        </div>
      </div>
    </header>
    <div class="bsa-cpc"></div>
    <main>
      <div class="center">
        <div class="docs-nav">
          <div class="docs-nav-toggle"><span></span><span></span><span></span></div>
          <ul>
            <li>
              <div class="title">Get Started</div>
              <ul>
                <li><a href="introduction.html">Introduction</a></li>
                <li><a href="kitchen-sink.html">Kitchen Sink</a></li>
                <li><a href="installation.html">Installation</a></li>
                <li><a href="app-layout.html">App HTML Layout</a></li>
                <li><a href="rtl-layout.html">RTL Layout</a></li>
                <li><a href="init-app.html">Initialize App</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Events</div>
              <ul>
                <li><a href="events.html">Events</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Router / Navigation</div>
              <ul>
                <li><a href="routes.html">Routes</a></li>
                <li><a href="router-component.html">Router Component</a></li>
                <li><a href="view.html#router-api-methods-properties">Router API</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Components</div>
              <ul>
                <li><a href="app.html">App / Core</a></li>
                <li><a href="accordion.html">Accordion / Collapsible</a></li>
                <li><a href="action-sheet.html">Action Sheet / Actions</a></li>
                <li><a href="autocomplete.html">Autocomplete</a></li>
                <li><a href="badge.html">Badge</a></li>
                <li><a href="block.html">Block / Content Block</a></li>
                <li><a href="button.html">Button</a></li>
                <li><a href="calendar.html">Calendar / Datepicker</a></li>
                <li><a href="cards.html">Cards</a></li>
                <li><a href="checkbox.html">Checkbox</a></li>
                <li><a href="chips.html">Chips / Tags</a></li>
                <li><a href="contacts-list.html">Contacts List</a></li>
                <li><a href="data-table.html">Data Table</a></li>
                <li><a href="dialog.html">Dialog</a></li>
                <li><a href="elevation.html">Elevation</a></li>
                <li><a href="floating-action-button.html">Floating Action Button / FAB</a></li>
                <li><a href="form.html">Form Data / Storage</a></li>
                <li><a href="gauge.html">Gauge</a></li>
                <li><a href="grid.html">Grid / Layout Grid</a></li>
                <li><a href="icons.html">Icons</a></li>
                <li><a href="infinite-scroll.html">Infinite Scroll</a></li>
                <li><a href="inputs.html">Inputs / Form Inputs</a></li>
                <li><a href="lazy-load.html">Lazy Load</a></li>
                <li><a href="link.html">Link</a></li>
                <li><a href="list-view.html">List View</a></li>
                <li><a href="list-index.html">List Index</a></li>
                <li><a href="login-screen.html">Login Screen</a></li>
                <li><a href="messagebar.html">Messagebar</a></li>
                <li><a href="messages.html">Messages</a></li>
                <li><a href="navbar.html">Navbar</a></li>
                <li><a href="notification.html">Notification</a></li>
                <li><a href="page.html">Page</a></li>
                <li><a href="panel.html">Panel / Side Panels</a></li>
                <li><a href="photo-browser.html">Photo Browser</a></li>
                <li><a href="picker.html">Picker</a></li>
                <li><a href="popover.html">Popover</a></li>
                <li><a href="popup.html">Popup</a></li>
                <li><a href="preloader.html">Preloader</a></li>
                <li><a href="progressbar.html">Progressbar</a></li>
                <li><a href="pull-to-refresh.html">Pull to Refresh</a></li>
                <li><a href="radio.html">Radio</a></li>
                <li><a href="range-slider.html">Range Slider</a></li>
                <li><a href="searchbar.html">Searchbar</a></li>
                <li><a href="sheet-modal.html">Sheet Modal</a></li>
                <li><a href="smart-select.html">Smart Select</a></li>
                <li><a href="sortable-list.html">Sortable List</a></li>
                <li><a href="statusbar.html">Statusbar</a></li>
                <li><a href="stepper.html">Stepper</a></li>
                <li><a href="subnavbar.html">Subnavbar</a></li>
                <li><a href="swiper.html">Swiper</a></li>
                <li><a href="swipeout.html">Swipeout</a></li>
                <li><a href="tabs.html">Tabs</a></li>
                <li><a href="timeline.html">Timeline</a></li>
                <li><a href="toast.html">Toast</a></li>
                <li><a href="toggle.html">Toggle</a></li>
                <li><a href="toolbar-tabbar.html">Toolbar / Tabbar</a></li>
                <li><a href="tooltip.html">Tooltip</a></li>
                <li><a href="vi.html">Video Intelligence (vi)</a></li>
                <li><a href="view.html">View / Router</a></li>
                <li><a href="virtual-list.html">Virtual List</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Framework7 Icons</div>
              <ul>
                <li><a href="/icons/">Framework7 Icons Cheatsheet</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Styling</div>
              <ul>
                <li><a href="iphone-x.html">iPhone X</a></li>
                <li><a href="color-themes.html">Color Themes</a></li>
                <li><a href="typography.html">Typography</a></li>
                <li><a href="hairlines.html">Hairlines</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Dom7</div>
              <ul>
                <li><a href="dom7.html">Dom7</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Template7</div>
              <ul>
                <li><a href="template7.html">Template7</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Fast Clicks</div>
              <ul>
                <li><a href="fast-clicks.html">Fast Clicks</a></li>
                <li><a href="active-state.html">Active State</a></li>
                <li><a href="tap-hold.html">Tap Hold Event (Long Tap)</a></li>
                <li><a href="touch-ripple.html">Touch Ripple (MD Theme)</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Utilities</div>
              <ul>
                <li><a href="request.html">Request / Ajax</a></li>
                <li><a href="utils.html">Utils</a></li>
                <li><a href="device.html">Device</a></li>
                <li><a href="support.html">Support</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Plugins API</div>
              <ul>
                <li><a href="plugins-api.html">Plugins API</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Lazy Modules</div>
              <ul>
                <li><a href="lazy-modules.html">Lazy Modules</a></li>
              </ul>
            </li>
            <li>
              <div class="title">Custom Build</div>
              <ul>
                <li><a href="custom-build.html">Custom Build</a></li>
              </ul>
            </li>
          </ul>
        </div>
        <div class="docs-content">
          <div class="improve-docs-link"><a href="https://github.com/gzxishan/framework7-websitev3/edit/master/src/pug/undefined" target="_blank">Improve this Doc</a></div>
          <h1>Events</h1>
          <ul class="docs-index"></ul>
          <p>Most of Framework7 components that is built with classes/constructors (including Framework7 class itself) have kind of event emitter API.</p>
          <p>It allows us easily to emit and handle all kind of events, including events between components.</p>
          <h2>Events Handlers in Parameters</h2>
          <p>When you create app instance or any other component using API, you can pass event handler on app/component initialization in <code><b>on</b></code> parameter:</p><pre><code class="js"><span class="token keyword">var</span> app <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Framework7</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token operator">...</span>
  on<span class="token punctuation">:</span> <span class="token punctuation">{</span>
    <span class="token comment">// each object key means same name event handler</span>
    <span class="token function-variable function">pageInit</span><span class="token punctuation">:</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">page</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token comment">// do something on page init</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token function-variable function">popupOpen</span><span class="token punctuation">:</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token comment">// do something on popup open</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">var</span> popup <span class="token operator">=</span> app<span class="token punctuation">.</span>popup<span class="token punctuation">.</span><span class="token function">create</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token operator">...</span>
  on<span class="token punctuation">:</span> <span class="token punctuation">{</span>
    <span class="token function-variable function">open</span><span class="token punctuation">:</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
      <span class="token comment">// do something on popup open</span>
    <span class="token punctuation">}</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span></pre></code>
          <h2>Events Methods</h2>
          <p>It also possible to add/remove event handlers using the following instance methods:</p>
          <table class="methods-table">
            <tbody>
              <tr>
                <td>[instance].on(<span>event</span>, <span>handler</span>)</td>
                <td>Add event handler</td>
              </tr>
              <tr>
                <td>[instance].once(<span>event</span>, <span>handler</span>)</td>
                <td>Add event handler that will be removed after it was fired</td>
              </tr>
              <tr>
                <td>[instance].off(<span>event</span>)</td>
                <td>Remove all handlers for specified event</td>
              </tr>
              <tr>
                <td>[instance].emit(<span>event</span>, <span>...args</span>)</td>
                <td>Fire event on instance</td>
              </tr>
            </tbody>
          </table>
          <h4>Add Event Handlers</h4><pre><code class="js"><span class="token keyword">var</span> app <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Framework7</span><span class="token punctuation">(</span><span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">var</span> popup <span class="token operator">=</span> app<span class="token punctuation">.</span>popup<span class="token punctuation">.</span><span class="token function">create</span><span class="token punctuation">(</span><span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'pageInit'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">page</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on page init</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'popupClose'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on popup open</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

popup<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'open'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on popup open</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// Once handler, will work only once</span>
popup<span class="token punctuation">.</span><span class="token function">once</span><span class="token punctuation">(</span><span class="token string">'close'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on popup close</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></pre></code>
          <h4>Add Multiple Handlers</h4>
          <p>We can pass multiple events in first parameters separated with space:</p><pre><code class="js">app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'popupOpen popupClose'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">popup</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on popupOpen and popupClose</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></pre></code>
          <h4>Remove Event Handlers</h4>
          <p>Named function handler can be removed:</p><pre><code class="js"><span class="token keyword">function</span> <span class="token function">onTabShow</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token comment">// do something on tab show</span>
<span class="token punctuation">}</span>

<span class="token comment">// add handler</span>
app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'tabShow'</span><span class="token punctuation">,</span> onTabShow<span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token comment">// later remove tabShow handler:</span>
app<span class="token punctuation">.</span><span class="token function">off</span><span class="token punctuation">(</span><span class="token string">'tabShow'</span><span class="token punctuation">,</span> onTabShow<span class="token punctuation">)</span><span class="token punctuation">;</span></pre></code>
          <h4>Remove All Handlers</h4>
          <p>If we don't pass second handler argument to <code>.off</code> method then we will remove all handlers assigned for this event:</p><pre><code class="js"><span class="token comment">// Remove all tabShow handlers</span>
app<span class="token punctuation">.</span><span class="token function">off</span><span class="token punctuation">(</span><span class="token string">'tabShow'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></pre></code>
          <h4>Emit Events</h4>
          <p>And of course we can emit events and any kind of custom events we may need:</p><pre><code class="js">app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'myCustomEvent'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token parameter">a<span class="token punctuation">,</span> b</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token built-in">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>a<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// -> 'foo'</span>
  <span class="token built-in">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span>b<span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// -> 'bar'</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

app<span class="token punctuation">.</span><span class="token function">emit</span><span class="token punctuation">(</span><span class="token string">'myCustomEvent'</span><span class="token punctuation">,</span> <span class="token string">'foo'</span><span class="token punctuation">,</span> <span class="token string">'bar'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</pre></code>
          <h2>Events Delegating</h2>
          <p>Events which emitted on components will delegate to app instance as well:</p><pre><code class="js">app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'something'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

popup<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'something'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

popup<span class="token punctuation">.</span><span class="token function">emit</span><span class="token punctuation">(</span><span class="token string">'something'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// will trigger "something" event assigned to both app and popup instances</span>
</pre></code>
          <p>If this is not what you want, it is possible to emit so called <b>local</b> events on components. In this case we need to prefix event name with <code><b>local::</b></code></p><pre><code class="js">app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'something'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

popup<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'something'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span><span class="token comment">/*...*/</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

popup<span class="token punctuation">.</span><span class="token function">emit</span><span class="token punctuation">(</span><span class="token string">'local::something'</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// will only trigger "something" event assigned to popup instance above</span>
</pre></code>
          <h2>Event Handler Context</h2>
          <p>Event handler context (<code>this</code>) will always point to instance where it was assigned:</p><pre><code class="js">app<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'popupOpen'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token built-in">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token context">this</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// -> app instance</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
popup<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'popupOpen'</span><span class="token punctuation">,</span> <span class="token keyword">function</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token built-in">console</span><span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token context">this</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// -> popup instance</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></pre></code>
        </div>
      </div>
    </main>
    <script src="/framework7-v3/js/jquery-1.11.0.min.js"></script>
    <script src="/framework7-v3/js/main.js"></script>
  </body>
</html>